Artemis Trouble Ticket API

(0 reviews)

API Data Dictionary - PATCH troubleTicket

This section defines the key fields used in the TMF621 Trouble Ticket API. Attributes listed here may appear in request or response payloads depending on the operation. Fields are derived from TMF621 v5.0.0 and follow TMF630 REST design principles.

API request payload

TMF621 recommends that PATCH requests include only the fields that require modification. In the current implementation, the API supports a custom merge-like update mechanism using the application/json content type. While TMF630 Part 5 describes three possible formats for patching — including:

JavaScript Object Notation Merge Patch (RFC 7396), indicated by setting the Content-Type HTTP request header to application/merge-patch+json
JavaScript Object Notation Patch (RFC 6902), indicated by setting the Content-Type HTTP request header to application/json-patch+json
TMF630 Part 5 custom query-patch format (optional/implementation-defined), using application/json-patch-query+json as the Content-Type

this implementation does not formally support any of the above. Instead, it follows a simplified merge-patch approach for top-level and object fields, but does not offer standard support for array operations or structured patch replay. As such, incoming PATCH requests should follow the documented custom format and include only the attributes to be updated.

Exception: Integration with InformationRequiredEvent Support

Although inbound requests must use application/json, the API does produce TroubleTicketInformationRequiredEvent with an informationRequired array detailing the patches in application/json-patch+json format. These messages:

Use RFC 6902 op, path, and value syntax for add and replace.
Are used to guide partners on what information must be submitted via PATCH
Indicate the server's expected intent, but are not always directly replayable as PATCH input unless value is provided in the event.

Each PATCH request must not include immutable fields, and any field included is subject to validation rules (e.g., conditional requirements).

Attributes allowed in PATCH operations:

Section	Field Name	Example Field Value	Description
HTTP Header Name	Correlation-ID	c97ded75-44fa-4b69-9f3b-01d513a41efe	A GUID to relate requests belonging to the same transaction
System attributes	id	INC01234567	Identifier of the ticket. Immutable.
Payload First Class Attribute	status	resolved	Ticket status to be updated. Allowed values: cancelled, inProgress
Payload First Class Attribute	statusChangeReason	No further action required	Explanation fortr>
Payload First Class Attribute	twentyFourHourAccess	true	Defines whether the EU will be available 24 hour in the event an appointment is required.
Payload First Class Attribute	earliestNextAccessDateTime	2025-01-02T09:00:00Z	Conditional, mandatory if twentyFourHourAccess is false.
Payload First Class Attribute	latestAccessDateTime	2025-01-01T17:00:00Z	Conditional, mandatory if twentyFourHourAccess is false.
Payload First Class Attribute	troubleTicketCharacteristic	See troubleTicketCharacteristic table	Update or add optional characteristics (e.g., faultType, frequency, traceRouteResults)
Payload First Class Attribute	attachment	See attachment table	Optional base64-encoded file (e.g., screenshot); 1 allowed per PATCH
Payload First Class Attribute	note	See note table	Append a public partner or end-user note
Payload First Class Attribute	relatedParty	See relatedParty table	Update reporting party or end-user contact details
Payload First Class Attribute	troubleTicketRelationship	See troubleTicketRelationship table	Add or update related tickets (e.g., parent, duplicateOf, causedBy)
Payload First Class Attribute	externalIdentifier	See externalIdentifier table	Add external references such as partner or supplier ticket numbers
Payload First Class Object	appointment	See appointment table	Reference to TMF646 appointment (id, href)

Once created, a ticket’s troubleTicketSpecification is immutable. It MUST be defined during POST /troubleTicket, and partners are not permitted to change it via PATCH.

Any attempt to modify or replace this attribute will be rejected with 403.

Other immutable and non-patchable Fields (Ignored if Updated)

Examples

{
  "id": "INC01234567",
  "status": "cancelled",
  "statusChangeReason": "No longer a Causal CI",
  "note": [
    {
      "text": "Problem no longer exists. Customer confirmed that from 2 pm he's not been experiencing any disservice.",
      "author": "Jane Smith",
      "source": "partner",
      "@type": "PartnerNote",
      "@baseType": "Note"
    }
  ],
  "@type": "PartnerTroubleTicket",
  "@baseType": "TroubleTicket"
}

[
  {
    "op": "add",
    "path": "/troubleTicketCharacteristic/value?troubleTicketCharacteristic.id=authoriseEngineerEffort",
    "value": true
  },
  {
    "op": "replace",
    "path": "/troubleTicketCharacteristic/value?troubleTicketCharacteristic.id=safetyNote",
    "value": "Ring the bell at the gate of the front garden to get access to the property. Beware there's a friendly dog running wild. It is not dangerous, though we advise to send an engineer not scared of dogs."
  }
]


[

  {

    "op": "replace",

    "path": "/appointment",

    "value": {

      "id": "APP123456",

      "@type": "AppointmentRef"

    }

  }

]

[

  {

"op": "replace",

"path": "/troubleTicketCharacteristic/value?troubleTicketCharacteristic.id=safetyNote",

"value": "Ring the bell at the gate of the front garden to get access to the property. Beware there's a friendly dog running wild. It is not dangerous, though we advise to send an engineer not scared of dogs."

  }

]


{

  "op": "replace",

  "path": "/troubleTicketCharacteristic/value?troubleTicketCharacteristic.id=safetyNote",

  "value": "Ring the bell at the gate of the front garden to get access to the property. Beware there's a friendly dog running wild. It is not dangerous, though we advise to send an engineer not scared of dogs."

}